|
Eclipse Platform Pre-release 3.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.eclipse.core.runtime.Plugin
The abstract superclass of all plug-in runtime class
implementations. A plug-in subclasses this class and overrides
the startup
and shutdown
methods
in order to react to life cycle requests automatically issued
by the platform.
Conceptually, the plug-in runtime class represents the entire plug-in rather than an implementation of any one particular extension the plug-in declares. A plug-in is not required to explicitly specify a plug-in runtime class; if none is specified, the plug-in will be given a default plug-in runtime object that ignores all life cycle requests (it still provides access to the corresponding plug-in descriptor).
In the case of more complex plug-ins, it may be desireable
to define a concrete subclass of Plugin
.
However, just subclassing Plugin
is not
sufficient. The name of the class must be explicitly configured
in the plug-in's manifest (plugin.xml
) file
with the class attribute of the <plugin>
element markup.
Instances of plug-in runtime classes are automatically created by the platform in the course of plug-in activation. Clients must never explicitly instantiate a plug-in runtime class.
A typical implementation pattern for plug-in runtime classes is to provide a static convenience method to gain access to a plug-in's runtime object. This way, code in other parts of the plug-in implementation without direct access to the plug-in runtime object can easily obtain a reference to it, and thence to any plug-in-wide resources recorded on it. An example follows:
package myplugin; public class MyPluginClass extends Plugin { private static MyPluginClass instance; public static MyPluginClass getInstance() { return instance; } public void MyPluginClass(IPluginDescriptor descriptor) { super(descriptor); instance = this; // ... other initialization } // ... other methods }In the above example, a call to
MyPluginClass.getInstance()
will always return an initialized instance of MyPluginClass
.
The static method Platform.getPlugin()
can be used to locate a plug-in's runtime object by name.
The extension initialization would contain the following code:
Plugin myPlugin = Platform.getPlugin("com.example.myplugin");Another typical implementation pattern for plug-in classes is handling of any initialization files required by the plug-in. Typically, each plug-in will ship one or more default files as part of the plug-in install. The executing plug-in will use the defaults on initial startup (or when explicitly requested by the user), but will subsequently rewrite any modifications to the default settings into one of the designated plug-in working directory locations. An example of such an implementation pattern is illustrated below:
package myplugin; public class MyPlugin extends Plugin { private static final String INI = "myplugin.ini"; private Properties myProperties = null; public void startup() throws CoreException { try { InputStream input = null; // look for working properties. If none, use shipped defaults File file = getStateLocation().append(INI).toFile(); if (!file.exists()) { URL base = getDescriptor().getInstallURL(); input = (new URL(base,INI)).openStream(); } else input = new FileInputStream(file); // load properties try { myProperties = new Properties(); myProperties.load(input); } finally { try { input.close(); } catch (IOException e) { // ignore failure on close } } } catch (Exception e) { throw new CoreException( new Status(IStatus.ERROR, getDescriptor().getUniqueIdentifier(), 0, "Problems starting plug-in myplugin", e)); } } public void shutdown() throws CoreException { // save properties in plugin state location (r/w) try { FileOutputStream output = null; try { output = new FileOutputStream(getStateLocation().append(INI)); myProperties.store(output, null); } finally { try { output.close(); } catch (IOException e) { // ignore failure on close } } } catch (Exception e) { throw new CoreException( new Status(IStatus.ERROR, getDescriptor().getUniqueIdentifier(), 0, "Problems shutting down plug-in myplugin", e)); } } public Properties getProperties() { return myProperties; } }
Field Summary | |
protected org.osgi.framework.Bundle |
bundle
The bundle associated this plug-in |
static String |
PREFERENCES_DEFAULT_OVERRIDE_BASE_NAME
The name of the file (value "preferences.ini" ) in a
plug-in's (read-only) directory that, when present, contains values that
override the normal default values for this plug-in's preferences. |
static String |
PREFERENCES_DEFAULT_OVERRIDE_FILE_NAME
|
Constructor Summary | |
Plugin()
Creates a new plug-in runtime object. |
|
Plugin(org.osgi.framework.BundleContext context)
Creates a new plug-in runtime object associated with the given bundle context. |
|
Plugin(IPluginDescriptor descriptor)
Creates a new plug-in runtime object for the given plug-in descriptor. |
Method Summary | |
URL |
find(IPath path)
Returns a URL for the given path. |
URL |
find(IPath path,
Map override)
Returns a URL for the given path. |
org.osgi.framework.Bundle |
getBundle()
Returns the bundle |
IPluginDescriptor |
getDescriptor()
Returns the plug-in descriptor for this plug-in runtime object. |
ILog |
getLog()
Returns the log for this plug-in. |
Preferences |
getPluginPreferences()
Returns the preference store for this plug-in. |
IPath |
getStateLocation()
Returns the location in the local file system of the plug-in state area for this plug-in. |
protected void |
initializeDefaultPluginPreferences()
Initializes the default preferences settings for this plug-in. |
boolean |
isDebugging()
Returns whether this plug-in is in debug mode. |
InputStream |
openStream(IPath file)
Returns an input stream for the specified file. |
InputStream |
openStream(IPath file,
boolean localized)
Returns an input stream for the specified file. |
void |
savePluginPreferences()
Saves preferences settings for this plug-in. |
void |
setDebugging(boolean value)
Sets whether this plug-in is in debug mode. |
void |
shutdown()
Shuts down this plug-in and discards all plug-in state. |
void |
start(org.osgi.framework.BundleContext context)
Starts up this plug-in. |
void |
startup()
Starts up this plug-in. |
void |
stop(org.osgi.framework.BundleContext context)
Stops this plug-in. |
String |
toString()
Returns a string representation of the plug-in, suitable for debugging purposes only. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
protected org.osgi.framework.Bundle bundle
public static final String PREFERENCES_DEFAULT_OVERRIDE_BASE_NAME
"preferences.ini"
) in a
plug-in's (read-only) directory that, when present, contains values that
override the normal default values for this plug-in's preferences.
The format of the file is as per java.io.Properties
where
the keys are property names and values are strings.
public static final String PREFERENCES_DEFAULT_OVERRIDE_FILE_NAME
Constructor Detail |
public Plugin()
Plug-in runtime classes are BundleActivators
and so must
have an default constructor. This method is called by the runtime when the associated
bundle is being activated. The resultant instance is not managed by the runtime and
so should be remembered by the client (typically using a Singleton pattern).
This method will never be called for plug-ins operating in compatibility mode.
Clients must never explicitly call this method.
Note: The class loader typically has monitors acquired during invocation of this method. It is strongly recommended that this method avoid synchronized blocks or other thread locking mechanisms, as this would lead to deadlock vulnerability.
Note: This is an early access API to the new OSGI-based Eclipse 3.0 Platform Runtime. Because the APIs for the new runtime have not yet been fully stabilized, they should only be used by clients needing to take particular advantage of new OSGI-specific functionality, and only then with the understanding that these APIs may well change in incompatible ways until they reach their finished, stable form (post-3.0).
public Plugin(org.osgi.framework.BundleContext context)
Plug-in runtime classes are BundleActivators
and so must
have an default constructor.
Clients may call this method if they are not using this class as their bundle activator.
Note: The class loader typically has monitors acquired during invocation of this method. It is strongly recommended that this method avoid synchronized blocks or other thread locking mechanisms, as this would lead to deadlock vulnerability.
Note: This is an early access API to the new OSGI-based Eclipse 3.0 Platform Runtime. Because the APIs for the new runtime have not yet been fully stabilized, they should only be used by clients needing to take particular advantage of new OSGI-specific functionality, and only then with the understanding that these APIs may well change in incompatible ways until they reach their finished, stable form (post-3.0).
context
- the bundle contextpublic Plugin(IPluginDescriptor descriptor)
Instances of plug-in runtime classes are automatically created by the platform in the course of plug-in activation. Clients must never explicitly call this method.
Note: The class loader typically has monitors acquired during invocation of this method. It is strongly recommended that this method avoid synchronized blocks or other thread locking mechanisms, as this would lead to deadlock vulnerability.
Note: This is obsolete API that will be replaced in time with the OSGI-based Eclipse Platform Runtime introduced with Eclipse 3.0. This API will be deprecated once the APIs for the new Eclipse Platform Runtime achieve their final and stable form (post-3.0).
descriptor
- the plug-in descriptorgetDescriptor()
Method Detail |
public final URL find(IPath path)
null
if the URL
could not be computed or created.
null
public final URL find(IPath path, Map override)
null
if the URL
could not be computed or created.
path
- file path relative to plug-in installation locationoverride
- map of override substitution arguments to be used for
any $arg$ path elements. The map keys correspond to the substitution
arguments (eg. "$nl$" or "$os$"). The resulting
values must be of type java.lang.String. If the map is null
,
or does not contain the required substitution argument, the default
is used.
null
public final IPluginDescriptor getDescriptor()
Note: This is obsolete API that will be replaced in time with the OSGI-based Eclipse Platform Runtime introduced with Eclipse 3.0. This API will be deprecated once the APIs for the new Eclipse Platform Runtime achieve their final and stable form (post-3.0).
public final ILog getLog()
public final IPath getStateLocation()
The plug-in state area is a file directory within the platform's metadata area where a plug-in is free to create files. The content and structure of this area is defined by the plug-in, and the particular plug-in is solely responsible for any files it puts there. It is recommended for plug-in preference settings and other configuration parameters.
public final Preferences getPluginPreferences()
Note that if an error occurs reading the preference store from disk, an empty preference store is quietly created, initialized with defaults, and returned.
Calling this method may cause the preference store to be created and
initialized. Subclasses which reimplement the
initializeDefaultPluginPreferences
method have this opportunity
to initialize preference default values, just prior to processing override
default values imposed externally to this plug-in (specified for the product,
or at platform start up).
After settings in the preference store are changed (for example, with
Preferences.setValue
or setToDefault
),
savePluginPreferences
should be called to store the changed
values back to disk. Otherwise the changes will be lost on plug-in
shutdown.
savePluginPreferences()
,
Preferences.setValue(java.lang.String, boolean)
,
Preferences.setToDefault(java.lang.String)
public final void savePluginPreferences()
Plug-in preferences are not saved automatically on plug-in shutdown.
Preferences.store(java.io.OutputStream, java.lang.String)
,
Preferences.needsSaving()
protected void initializeDefaultPluginPreferences()
This method is called sometime after the preference store for this plug-in is created. Default values are never stored in preference stores; they must be filled in each time. This method provides the opportunity to initialize the default values.
The default implementation of this method does nothing. A subclass that needs to set default values for its preferences must reimplement this method. Default values set at a later point will override any default override settings supplied from outside the plug-in (product configuration or platform start up).
public boolean isDebugging()
public final InputStream openStream(IPath file) throws IOException
file
- path relative to plug-in installation location
IOException
openStream(IPath,boolean)
public final InputStream openStream(IPath file, boolean localized) throws IOException
The caller must close the returned stream when done.
file
- path relative to plug-in installation locationlocalized
- true
for the localized version
of the file, and false
for the file exactly
as specified
IOException
public void setDebugging(boolean value)
value
- whether or not this plugi-in is in debug modepublic void shutdown() throws CoreException
This method should be re-implemented in subclasses that need to do something when the plug-in is shut down. Implementors should call the inherited method to ensure that any system requirements can be met.
Plug-in shutdown code should be robust. In particular, this method should always make an effort to shut down the plug-in. Furthermore, the code should not assume that the plug-in was started successfully, as this method will be invoked in the event of a failure during startup.
Note 1: If a plug-in has been started, this method will be automatically invoked by the platform when the platform is shut down.
Note 2: This method is intended to perform simple termination of the plug-in environment. The platform may terminate invocations that do not complete in a timely fashion.
Clients must never explicitly call this method.Note: This is obsolete API that will be replaced in time with the OSGI-based Eclipse Platform Runtime introduced with Eclipse 3.0. This API will be deprecated once the APIs for the new Eclipse Platform Runtime achieve their final and stable form (post-3.0).
CoreException
- if this method fails to shut down
this plug-inpublic void startup() throws CoreException
This method should be overridden in subclasses that need to do something when this plug-in is started. Implementors should call the inherited method to ensure that any system requirements can be met.
If this method throws an exception, it is taken as an indication that plug-in initialization has failed; as a result, the plug-in will not be activated; moreover, the plug-in will be marked as disabled and ineligible for activation for the duration.
Plug-in startup code should be robust. In the event of a startup failure,
the plug-in's shutdown
method will be invoked automatically,
in an attempt to close open files, etc.
Note 1: This method is automatically invoked by the platform the first time any code in the plug-in is executed.
Note 2: This method is intended to perform simple initialization of the plug-in environment. The platform may terminate initializers that do not complete in a timely fashion.
Note 3: The class loader typically has monitors acquired during invocation of this method. It is strongly recommended that this method avoid synchronized blocks or other thread locking mechanisms, as this would lead to deadlock vulnerability.
Clients must never explicitly call this method.Note: This is obsolete API that will be replaced in time with the OSGI-based Eclipse Platform Runtime introduced with Eclipse 3.0. This API will be deprecated once the APIs for the new Eclipse Platform Runtime achieve their final and stable form (post-3.0).
CoreException
- if this plug-in did not start up properlypublic String toString()
public void start(org.osgi.framework.BundleContext context) throws Exception
This method should be overridden in subclasses that need to do something when this plug-in is started. Implementors should call the inherited method at the first possible point to ensure that any system requirements can be met.
If this method throws an exception, it is taken as an indication that plug-in initialization has failed; as a result, the plug-in will not be activated; moreover, the plug-in will be marked as disabled and ineligible for activation for the duration.
Plug-in startup code should be robust. In the event of a startup failure,
the plug-in's shutdown
method will be invoked automatically,
in an attempt to close open files, etc.
Note 1: This method is automatically invoked by the platform the first time any code in the plug-in is executed.
Note 2: This method is intended to perform simple initialization of the plug-in environment. The platform may terminate initializers that do not complete in a timely fashion.
Note 3: The class loader typically has monitors acquired during invocation of this method. It is strongly recommended that this method avoid synchronized blocks or other thread locking mechanisms, as this would lead to deadlock vulnerability.
Note 4: This method is not called on plug-ins operating in compatibility mode.
Clients must never explicitly call this method.Note: This is an early access API to the new OSGI-based Eclipse 3.0 Platform Runtime. Because the APIs for the new runtime have not yet been fully stabilized, they should only be used by clients needing to take particular advantage of new OSGI-specific functionality, and only then with the understanding that these APIs may well change in incompatible ways until they reach their finished, stable form (post-3.0).
start
in interface org.osgi.framework.BundleActivator
org.osgi.framework.BundleException
- if this plug-in did not start up properly
Exception
public void stop(org.osgi.framework.BundleContext context) throws Exception
This method should be re-implemented in subclasses that need to do something when the plug-in is shut down. Implementors should call the inherited method as late as possible to ensure that any system requirements can be met.
Plug-in shutdown code should be robust. In particular, this method should always make an effort to shut down the plug-in. Furthermore, the code should not assume that the plug-in was started successfully, as this method will be invoked in the event of a failure during startup.
Note 1: If a plug-in has been started, this method will be automatically invoked by the platform when the platform is shut down.
Note 2: This method is intended to perform simple termination of the plug-in environment. The platform may terminate invocations that do not complete in a timely fashion.
Note 3: This method is not called on plug-ins operating in compatibility mode.
Clients must never explicitly call this method.Note: This is an early access API to the new OSGI-based Eclipse 3.0 Platform Runtime. Because the APIs for the new runtime have not yet been fully stabilized, they should only be used by clients needing to take particular advantage of new OSGI-specific functionality, and only then with the understanding that these APIs may well change in incompatible ways until they reach their finished, stable form (post-3.0).
stop
in interface org.osgi.framework.BundleActivator
org.osgi.framework.BundleException
- if this method fails to shut down
this plug-in
Exception
public org.osgi.framework.Bundle getBundle()
Note: This is an early access API to the new OSGI-based Eclipse 3.0 Platform Runtime. Because the APIs for the new runtime have not yet been fully stabilized, they should only be used by clients needing to take particular advantage of new OSGI-specific functionality, and only then with the understanding that these APIs may well change in incompatible ways until they reach their finished, stable form (post-3.0).
|
Eclipse Platform Pre-release 3.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |